home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 51 / Amiga Format CD51 (2000-03-10)(Future Publishing)(GB)[!][issue 2000-04].iso / -in_the_mag- / freedos / freedos_docs / mini / emacs-mint.txt < prev    next >
Text File  |  2000-02-08  |  14KB  |  348 lines
  1.         The Freemacs extension writer's guide to MINT functions.
  2.  
  3. Introduction:
  4.  
  5.     This document purports to explain how an ordinary person may be
  6. transformed into a Freemacs wizard.  In doing so, only those functions
  7. that are called by a wizard will be explained.  Function that are called
  8. only by other functions and functions bound to keys will not be explained
  9. There is no prohibition against calling them yourself, but they are not
  10. documented.
  11.  
  12.  
  13. Assumptions:
  14.  
  15.     You are assumed to be familiar with the operation of the Freemacs
  16. editor.  You are also assumed to have read the tutorial for the MINT
  17. language.
  18.  
  19. Notation:
  20.  
  21.     When a specific function is referred to, it will be expressed as
  22. a MINT active default function.  Arguments to the function will be given
  23. only if they are  referred to.  When a MINT string that is not a function
  24. is referred  to, it will be expressed as a neutral default function.  A
  25. string of capital letters means what it says, which is either obvious
  26. from the context, or explained in the surrounding text.  Other strings
  27. will be set off by double quotes.
  28.     Examples:
  29.  
  30.     #(Fbuffer-fn) refers to the function "buffer-fn" in library F.
  31.     ##(lib-list) refers to the contents of the string "lib-list".
  32.     ##(filename.BUFFER NUMBER) refers to the contents of the string
  33.       having the name "filename." concatenated with a buffer number.
  34.  
  35.  
  36. Arguments:
  37.  
  38.     Every function whose name is #(X:x-x-x), that is to say, every
  39. function whose second character is ':' is executable by the user.  Each
  40. function may be passed one argument or not.  If the function knows how to
  41. deal with an argument, then the function begins with a TAB.  Functions
  42. that don't know how to deal with an argument may safely be repeated using
  43. #(Floop).
  44.  
  45.  
  46. Filenames:
  47.  
  48.     Each buffer has a filename associated with it.  This filename is
  49. held in #(buffer-fn.BUFFER) where BUFFER is the buffer number.
  50. ##(Fdefault-ext) contains the extension used whenever a filename doesn't
  51. specify an extension.
  52.  
  53.  
  54. Libraries:
  55.  
  56.     A library is a disk file that contains MINT strings stored in a
  57. special form.  Strings whose name begins in a capital letter, called the
  58. library letter, belong to a library.  The filename of the library is held in
  59. ##(LIBRARY LETTERfilename).  A library stored on disk contains
  60. only strings whose names begin with the library letter and ##(lib-name),
  61. a string that contains just the library letter.  This is done so that the
  62. library letter of a just loaded library may be easily determined.  A list
  63. of the library letters of all loaded libraries is in ##(lib-list).  The last
  64. library loaded is the first letter in ##(lib-list).
  65.     A library is loaded with #(Fload-lib,FILENAME).  A library is
  66. saved with #(Fsave-lib,FILENAME).  All the libraries may be saved in their
  67. respective files using #(F:save-all-libs).  After a library is loaded #(LIBRARY
  68. LETTER&setup) is executed, which performs whatever initialization is
  69. required by the library.
  70.     If the string ##(LIB LETTERmodified) exists, then the library has
  71. been modified and should be saved to disk.  #(F:save-all-libs) will save
  72. any libs that have been modified.
  73.  
  74.  
  75. Buffers:
  76.  
  77.     Freemacs initially fires up with only one buffer, numbered one
  78. However, Freemacs needs a buffer for its own use, the edit buffer, so it
  79. creates another buffer which is numbered two.
  80.     ##(buffer-mode.BUFFER NUMBER) contains the mode of the buffer.
  81. ##(buffer-name.BUFFER NAME) contains the name of the buffer (eg.  foo,
  82. *scratch*, *mint-edit* , etc).  This type should always be four characters
  83. long.  ##(buffer-filename.BUFFER NUMBER) contains the filename of the
  84. buffer.  If the buffer has no filename then the string will not exist.
  85.     #(Ffor-all-buffers,STRING) will execute the function named in
  86. STRING for every user buffer.  Equivalent to #(ba,2)STRING #(ba,3)STRING,
  87. etc. for all the buffers that exist.  #(Fbuffer-modified,YES,NO) executes
  88. YES if the buffer has been modified, otherwise it executes NO.
  89. #(Fsave-buffer if modified) will save the buffer into
  90. ##(buffer-filename).tmp if the buffer has been modified.
  91. #(Fok-to-trash-buffer,FUNCTIONS) asks the user if it is ok to trash the
  92. buffer.  If the user responds with 'yes', then FUNCTIONS is executed.
  93.  
  94. #(Fuse-edit-buffer) will switch to the edit buffer.  You may insert
  95. anything into the edit buffer that doesn't cause problems with #(Mstring-read)
  96. #(Ftrash-buffer) gives the user a chance to save unsaved changes.
  97.  
  98.  
  99. Editing a string:
  100.  
  101.     A string may be edited using #(M:ef,STRING).  This causes an EDIT
  102. buffer (See "Buffers") to be selected and the string brought into the
  103. buffer for editing.  #(M:ef,STRING) actually selects all strings whose
  104. name starts with STRING.  This is a useful property since related
  105. functions share a common prefix on their names.  Additional strings may
  106. be edited by using #(M:ef,STRING) again.  #(M:give-name,STRING) enters a
  107. null definition for STRING.
  108.     Once the string is in the edit buffer, it may be edited like
  109. ordinary text.  When you are satisfied with the changes, you may execute
  110. #(M:done-editing).  This causes the strings to be redefined with the new
  111. contents.  If you are not satisfied with the changes and wish to throw
  112. them away, simply delete the entire string, name and all.
  113.     If the string ##(LIB LETTERmodified) exists, then the library has
  114. been modified and should be saved to disk.  #(F:save-all-libs) will save
  115. any libs that have been modified.
  116.  
  117.  
  118.  
  119. Initialization:
  120.  
  121.     #(F&setup) is the first function executed after loading the
  122. library "emacs.ed".  #(lib-list) is initialized to contain only "F", the
  123. rest of the MS-DOS command line is processed, and three special strings
  124. are defined.  These two strings are #(d), #(g), and #(k).  These strings
  125. are executed by the idling string (See "The Freemacs Reference Manual").
  126. #(d) has one argument, the name of a key, which it then processes.  #(g)
  127. waits for a key to be input and returns its value.  #(k) redisplays the
  128. screen and updates the mode line.
  129.  
  130. This is the function executed when emacs first starts up:
  131.  
  132. #(rd)#(ow,(
  133. Freemacs, a programmable editor - Version )##(lv,vn)(
  134. Copyright (C) Russell Nelson 1986-1988
  135. ))
  136. #(ds,Farglist,(SELF,arg1,arg2,arg3,arg4,arg5,arg6,arg7,arg8,arg9))
  137. #(ds,Fsearch-path,(#(SELF-do,##(fm,env.PATH,;,(##(gn,env.PATH,1000))))
  138. #(rs,env.PATH)))
  139. #(mp,Fsearch-path,#(Farglist))
  140. #(ds,Fsearch-path-do,(#(==,arg1,,,(
  141.     #(==,#(ff,arg1\emacs.ed,;),,(
  142.         #(SELF,##(fm,env.PATH,;,(##(gn,env.PATH,1000))))
  143.     ),(#(ds,env.EMACS,arg1\)))
  144. ))))
  145. #(mp,Fsearch-path-do,#(Farglist))
  146. #(ev)
  147. #(n?,env.EMACS,(
  148.     #(gn,env.EMACS,#(--,#(nc,##(env.EMACS)),1))
  149.     #(==,##(go,env.EMACS),\,,(
  150.         #(ow,(
  151. The EMACS environment variable must end with \ - Press any key to return to DOS
  152. ))
  153.         #(it,10000)#(hl,1)
  154.     ))
  155.     #(rs,env.EMACS)
  156. ))
  157. #(n?,env.EMACS,,(#(Fsearch-path)))
  158. #(n?,env.EMACS,,(#(==,#(ff,\emacs15\emacs.ed,;),,,(#(ds,env.EMACS,\emacs15\)))))
  159. #(n?,env.EMACS,,(#(==,#(ff,\emacs\emacs.ed,;),,,(#(ds,env.EMACS,\emacs\)))))
  160. #(an,Loading #(env.EMACS)emacs.ed...)
  161. #(==,#(ll,#(env.EMACS)emacs.ed),,(
  162.     #(an,Starting editor...)
  163.     #(##(lib-name)&setup)
  164. ),(
  165.     #(an)
  166.     #(ow,(
  167. Cannot find emacs.ed - Set the environment string EMACS to the subdirectory
  168. containing the Freemacs .ed files.  For example, EMACS=c:\freemacs\
  169. Press any key to return to DOS...))
  170.     #(it,10000)#(hl,1)
  171. ))
  172.  
  173.  
  174. Key bindings:
  175.  
  176.     There is a special library for key bindings, K (filename keys.ed).
  177. This is done so that a user can develop their own key bindings without
  178. changing the 'emacs' library.  Keyboard macros saved with
  179. #(F:name-kbd-macro,NAME) get placed into the K library.
  180.     When a key is pressed, the function associated with that key is
  181. executed.  If there is no function associated with that key,
  182. #(Fself-insert) is executed.  A function is associated with a key if
  183. #(K.KEY) exists.  #(F:bind-to-key,FUNC,KEY) will assign FUNC to KEY, and
  184. will prompt if either is missing.  This is done by defining a string
  185. #(K.KEY) to be "FUNC".  #(F:unbind-key) will prompt for a key and delete
  186. #(K.KEY).
  187.     The function #(M:keys-edit) will create an EDIT buffer (See
  188. "buffers") and insert all the key bindings into it.  The function
  189. #(M:keys-read) will read them out again.
  190.  
  191.  
  192. Marks:
  193.  
  194.     A ring of global marks is kept.  This is done by allocating
  195. sixteen global marks @ through F, and running through them one at a time
  196. The current mark is ##(Fmark).  Whenever a function moves point  off of
  197. the screen, a new global mark is set.  #(Fset-new-mark,MARK) will
  198. increment ##(Fmark), wrapping F around to @, and set the new mark to
  199. MARK.  #(Fexchange-point-and-mark) will do just that.
  200.  
  201.  
  202. Regions:
  203.  
  204.     All the text between the point and the current mark (See Marks)
  205. is considered a region.  #(Fregion-chars,FUNC) will process the region
  206. character by character by applying the function and insert the results
  207. again.  The function maps a decimal representation of a character into a
  208. decimal representation of a character.  #(F:lowercase-region) is an
  209. example of this type of function.
  210.  
  211.  
  212. User input:
  213.  
  214.     Functions need to prompt for and accept input from the user.
  215. #(Freadline,PROMPT,ACTION,HELP,MODE) does just that.  The user is
  216. prompted with the string PROMPT.  The user types a string (typically) and
  217. hits return, at which time ACTION is executed with ##(value) equal to the
  218. string that the user input.  ACTION usually consists of a number of MINT
  219. functions.  The user is given an initial value that he may accept or
  220. reject in ##(value).  Any key other than return rejects the initial value.
  221.     #(Freadline) causes the user to enter into a temporary mode, in
  222. which his keystrokes are interpreted differently.  If #(MODE.KEY) exists,
  223. it is executed else if #(Freadline.KEY) exists, it is executed, otherwise
  224. #(Freadline.other) is executed.
  225.  
  226. #(Fextended-command.C-[) completes a string name
  227. #(Fextended-command.?) lists string names that match the current string.
  228.  
  229. #(Freadline.C-h) deletes a character.
  230. #(Freadline.Delete) deletes a character.
  231. #(Freadline.other) processes all undefined characters.
  232. #(Freadline.C-l) brings in the character following point.
  233. #(Freadline.C-o) brings in the word following point.
  234. #(Freadline.C-u) aborts the input.
  235. #(Freadline.C-c) aborts the input.
  236. #(Freadline.C-m) accepts the input and executes ACTION.
  237.  
  238.  
  239. Looping:
  240.  
  241.     #(Floop,VALUE,COUNT) will rescan VALUE COUNT times.
  242.  
  243.  
  244. Values:
  245.  
  246.     Sometimes a function needs to be executed for its side effects,
  247. and its return value should be discarded.  For example, #(ba,x) sets the
  248. current buffer to x and returns x.  Usually you do not need the return
  249. value, so a standard non-existant string is executed, #(..,#(ba,x)).
  250. Since #(..) doesn't exist, a null value is returned.
  251.  
  252.  
  253.  
  254. Rings:
  255.  
  256.     Freemacs provided a facility for keeping a fixed size ring of
  257. strings.  At any one time one of the strings is considered to be at the
  258. head of the ring.  This string may be accessed using #(Fhead,RING) where
  259. RING is the name of the ring.  The size of the ring is kept in ##(FRING.size).
  260. The name of the string that is at the head of the string is ##(FRING.head).
  261. The ring may be rotated using #(Frotate,RING), and unrotated using
  262. #(Funrotate,RING).  The head of the ring may be modified by setting
  263. ##(value) to the desired value and executing #(Freplace head,RING).
  264. #(Fring,RING,SIZE) initializes a new ring.
  265.  
  266.  
  267. Killing:
  268.  
  269.     Freemacs provides a kill ring (See Rings) which keeps the last eight
  270. items killed.  The head of the ring may be inserted using #(Fun-kill).
  271. #(Fkill,MARK) may be used to kill from the point to MARK.  If ##(result)
  272. is "kill", the killed text is appended to the previous kill, otherwise
  273. the kill ring is rotated and a new kill is created.  #(F:append-next-kill)
  274. simply sets ##(result) to "kill" so that the next kill is appended.
  275. #(Fbackward-kill,MARK) is used to kill a string from MARK to the point.
  276. This preserves the order of killed text.
  277.     Rather than store the killed strings in the MINT string space,
  278. they are stored in buffer one, which is reserved by Freemacs for the kill
  279. buffer.  Marks @ through H are set on vertical bar characters ("|").  The
  280. eight strings are stored between the vertical bars.
  281.  
  282.  
  283.  
  284. Stacks:
  285.  
  286.     Any string may be turned into a stack using #(Fredefine,STRING,VAL).
  287. VAL must have balanced parentheses.  When the default or #(gs) built-in
  288. function is executed, the string seems to contain just VAL.  The previous
  289. contents may be restored using #(Funredefine,STRING).
  290.     One use of this may be seen in #(Fhit-any-key).
  291.  
  292.  
  293. Misc:
  294.  
  295. #(Fr,STRING,ARGS,...) will execute the string STRING with arguments ARGS.
  296. Before execution, STRING is parsed for arguments ARG1, ARG2, ... ARG9.
  297.  
  298. #(Fmax,A,B) returns the numerically greater of A and B.
  299.  
  300. #(Ftoupper,CHAR) maps ASCII values into ASCII values.  Only lower case
  301. letters are changed to upper case.
  302.  
  303. #(Ftolower,CHAR) maps ASCII values into ASCII values.  Only upper case
  304. letters are changed to lower case.
  305.  
  306. #(Fisupper,CHAR,YES,NO) tests the ASCII value of char and executes YES
  307. if the character is an upper case letter or NO if not.
  308.  
  309. #(Fpad-to-column,COL) will append enough tabs and spaces to the line to
  310. put the point at the given column.
  311.  
  312. #(Fy-or-n,PROMPT,YES,NO) will wait for a key and execute YES if
  313. that key is 'Y', or 'y'.  It will execute NO if the key is 'N' or 'n'.
  314. It keeps trying until a recognized key is hit.
  315.  
  316. #(Fyes-or-no,PROMPT,FUNCT) will wait for a line and execute FUNCT using #(Fr) if
  317. that line is 'yes' or 'no', supplying the result as the first argument (ARG1).
  318. Doesn't execute FUNCT if C-g (cancel) is pressed.  It keeps trying until a
  319. word is recognized.
  320.  
  321. #(Ferror,ERROR) will report ERROR as an error only if it is non-null.
  322.  
  323. ##(F-fill-column) is the column used by #(Fformat-paragraph)
  324.  
  325. ##(F-comment-column) is the column that comments should be aligned to.
  326.  
  327. #(Fmultiple,STRING,LIST) will execute #(STRING,LIST ELEMENT) where LIST
  328. consists of LIST ELEMENTS seperated by commas.  Note that LIST can not be
  329. scanned, otherwise the commas will be converted to argument seperators.  Use
  330. parentheses to protect LIST, or use a neutral function to return its results
  331. unscanned.
  332.  
  333. #(Fcase,arg1,
  334.     (new,(
  335.         stuff to scan if arg1 = new.
  336.     )),
  337.     (forward,(
  338.         stuff to scan if arg1 = forward.
  339.     )),
  340.     (backward,(
  341.         stuff to scan if arg1 = backward.
  342.     )),
  343.     (else,(
  344.         stuff to scan if arg1 isn't any of the above
  345.     ))
  346. )
  347.  
  348.